Public API

The runtime API is in BekaForge.AIProviders.Runtime. Assign a provider asset, create a typed prompt, then use a cancellable coroutine or build a request snapshot on the main thread and await the service. Provider assets contain endpoint configuration; API credentials are read from local credential storage.

Request path at a glance

Minimal HTTP/API editor request

Use this compact form for an editor or service workflow. Build the execution snapshot on Unity's main thread, then await the snapshot overload.

using System.Threading;
using System.Threading.Tasks;
using BekaForge.AIProviders.Runtime;

var request = LlmPromptRequest.CreateUserOnly("Hello!");
if (!AiProvidersService.TryBuildExecutionSnapshot(provider, request, out var snapshot, out var error))
{
    Debug.LogError(error);
    return;
}
var result = await AiProvidersService.SendPromptAsync(snapshot, cancellationToken);
if (result.Success) Debug.Log(result.ResponseText);
else Debug.LogError(result.Error);

The caller supplies a configured provider and cancellation token. Handle snapshot validation errors before sending, and do not access ScriptableObject provider fields from a worker thread.

Runtime component example

This example uses only the public runtime API. The provider asset is assigned in the Inspector; no key is embedded in code or the asset.

using BekaForge.AIProviders.Runtime;
using UnityEngine;

public sealed class DialogueHint : MonoBehaviour
{
    [SerializeField] private LlmProviderDefinitionBase provider;
    private PromptCoroutineHandle activeRequest;

    public void RequestHint(string dialogueText)
    {
        // Ignore duplicate submits until the current request completes or is cancelled.
        if (activeRequest != null) return;

        var prompt = LlmPromptRequest.CreateWithSystemPrompt(
            systemPrompt: "Suggest one concise, player-facing hint.",
            userPrompt: $"Dialogue context: {dialogueText}",
            temperature: 0.3f,
            maxTokens: 128);

        PromptCoroutineHandle requestHandle = null;
        requestHandle = AiProvidersService.BeginPromptCoroutine(provider, prompt,
            result =>
            {
                // An older or cancelled request must not clear a newer handle.
                if (activeRequest != requestHandle) return;
                if (result.Success) Debug.Log(result.ResponseText);
                else Debug.LogError($"{result.Error}\n{result.Diagnostic?.hint}");
                activeRequest = null;
            });
        activeRequest = requestHandle;
        StartCoroutine(requestHandle.Coroutine);
    }

    private void OnDisable()
    {
        var requestHandle = activeRequest;
        activeRequest = null;
        requestHandle?.Cancel();
    }
}

The example stores the returned handle before starting its coroutine and ignores duplicate submits while one is active. This also handles immediate validation failures: the completion callback can run as the coroutine starts. Clear the active handle before cancelling on teardown so a late callback cannot overwrite later state.

Async editor or service integration

using System.Threading;
using System.Threading.Tasks;
using BekaForge.AIProviders.Runtime;

public sealed class EditorSummaryService
{
    private readonly LlmProviderDefinitionBase provider;

    public EditorSummaryService(LlmProviderDefinitionBase provider) => this.provider = provider;

    public async Task SendAsync(
        CancellationToken cancellationToken)
    {
        // Call on Unity's main thread. Snapshot creation reads the provider asset.
        var prompt = LlmPromptRequest.CreateUserOnly(
            "Return a one-sentence summary.", maxTokens: 128);
        if (!AiProvidersService.TryBuildExecutionSnapshot(
                provider, prompt, out var snapshot, out var error))
        {
            return new AiProvidersService.PromptResult(false, string.Empty, error);
        }

        return await AiProvidersService.SendPromptAsync(snapshot, cancellationToken);
    }
}

Build the snapshot on the Unity main thread. This helper returns the nested AiProvidersService.PromptResult; let the caller decide how and where to present it. Each call starts an independent request, so a UI should prevent accidental duplicate submits or give each operation its own cancellation token.

Request and result types

• LlmPromptRequest.CreateUserOnly and CreateWithSystemPrompt create validated single-turn prompts. ToChatRequest() converts them to an ordered chat payload.
• LlmChatRequest carries messages, temperature, maxTokens, modelOverride, jsonMode, and stream.
• AiProvidersService.PromptResult reports Success, ResponseText, Error, Diagnostic, and token Usage when the provider returns it.
• AiProvidersService.RequestOptions configures timeout and transient retry behavior. Authentication and malformed-request failures are not retried as transient errors.

Profiles and editor-only connections

HTTP/API and local profile types include OpenAI, OpenAI Compatible, DeepSeek, Gemini, Ollama, and Custom JSON. Codex and Claude Code profiles are editor-only connections through separately installed native tools; they are not runtime provider assets for player builds. See Settings and Keys for credential handling and Request Pipeline for coroutine, streaming, and cancellation details.